Copyright: Copyright ® 1994, Philipp Bachmann


Contents

Getting started

Introduction

Installation

5 steps to creating a help file.

Procedures

Entering topics	Editing topics

Configuring the System	Configuring a Project

Creating a Manual

Reference

Menu Reference

Error Messages

Technical Support

Technical support may be obtained from the following sources:

International users:	CompuServe 100026,506

Australian users:	PBACHMAN @ OzEmail

Desperate users:	Phone/Fax: 61-3-804-5411


Introduction

WCS HelpDoc is for those who want to produce useful printed manuals and on-line help rapidly.

Feature List

Why use WCS HelpDoc?

5 steps to creating a help file

Compilation Output

Ordering Information

Copyright Notice


Feature List

WCS HelpDoc offers the following features.

•	Simplicity

•	Production of a User Manual and On-line help from a single source.

•	Integrated OLE support

•	Robust and reliable

•	Multi-user

•	Create hypertext jumps from within pictures, graphs, OLE objects painlessly.

•	Amazing auto-format features

•	Allows a first-time user to produce a fully-functionional Windows help file (HLP) with titles, browsing, searching and hypertext links AND a User Manual with glossary, contents, index, etc. in 30 minutes.


Why use WCS HelpDoc?


5 steps to creating a help file

Apart from the first, the steps outlined below do not have to be completed in any particular order.  It is possible, for example, to import topics into an existing help file after most of the topics and their associated text have been entered.

1. Create the Help Database (HDB) file

Select New from the File Menu.

2. (Optional) Import the Visual Basic mak file

This step is optional, and applies only to applications developed using Microsoft Visual Basic.  Select Import from the File Menu.

3. Enter/adjust topic names

Those who have imported topics from MS Visual Basic will have many of the necessary topics already created, while others will have to enter all topic names manually.

New topics are created by selecting New from the Topic Menu.

4. Add text/keywords to topics

Enter text for each topic in the Help text editor, and Keywords to the Keywords field.

5. Compile

The Windows Help file is created using the Create Help File option from the File Menu.

To create a manual by selecting Create Word Document from the File Menu.


Compilation Output

The compilation output screen provides a list of messages generated by the Help compiler.

It most common errors are:

1079 Out of file handles.

Especially when creating help files containing OLE objects, you'll need an enormous number of files to be defined in your config.sys.

4011 Context string <contextname> already used.

You have created two topics with similar names, resulting in duplicate context strings.  Change the topic name of one of these.

4113 Unresolved jump or popup <context name>

This will occur when you have created a hotspot which refers to a non-existant topic.

5059 Not enough memory to build Help file.

To free up memory, unload any unneeded applications, device drivers, and memory-resident programs.

Alternatively, switch from HC31.EXE to HCP.EXE (protected-mode help compiler).


Ordering Information

What will I get by purchasing this product?

•	Immediate notification of a password to disable slow start banner, nag screens, HelpDoc logo in help file.

•	A copy of the commercial version of WCS HelpDoc featuring:

-	Object compression - reduces disk space used by HelpDoc file by an average of 95 %.  Useful for HelpDoc files containing large screen shots.

-	More formatting options, including different bullet styles, lines etc.

-	Better navigation/maintenance facilities.

•	Free, prompt technical support facility through CompuServe.

•	A professionally bound, printed manual.

•	Notification (through CompuServe mail) of upgrades/bug fixes.

Price details

Price: $US93 + $6 freight

How to order WCS Developer’s Workbench

CompuServe:	Go SWREG and register the following product:

Registration ID:   2748

Program Title:     WCS HELPDOC 1.0

Mail:	Copy the following form (Select Copy from the menu and paste into Notepad or a word processor) and print it.

Name:_______________________________________________________

Company:____________________________________________________

Address1:____________________________________________________

Address2:____________________________________________________

City:________________________________________________________

State:_______________________________________________________

Zip:_________________________________________________________

Country:_____________________________________________________

Tel:___________________________________________________optional

Diskettes supplied are 3.5 inch.

Send completed form with payment to

Wonderful Computer Services

Mail Order Department

12/28 The Righi

South Yarra 3141

Australia


Copyright Notice

Information in this document is subject to change without notice.  No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without express written permission of the author.

Copyright © 1994  Philipp Bachmann

Microsoft, MS and MS-DOS are registered trademarks of Microsoft Corporation in the USA and other countries.

Visual Basic and Windows are trademarks of Microsoft Corporation in the USA and other countries.

CompuServe is a registered trademark of CompuServe, Inc.


Installation

There are separate installation procedures for the demonstration and commercial installations:

System Requirements

Demonstration Installation


System Requirements

•	Microsoft Windows graphical environment version 3.1 or later

•	PC using 386SX or higher microprocessor

•	Windows-compatible pointing device

•	4 Mb Ram

•	2 Mb free hard disk space.

•	Microsoft Windows Help Compiler

•	Microsoft Windows Hotspot Editor (optional)

•	(For demonstration version) Microsoft Visual Basic Professional 3.0.

•	(For creation of written documentation)Microsoft Word for Windows 6.0 or higher


Demonstration Installation

To install the demo, copy the following files to the directories indicated:

File	Directory

HELPDOC.HLP	Windows directory (typically C:\WINDOWS)

HELPDOC.EXE	Anywhere!

VSVBX.VBX	Windows System directory (typically C:\WINDOWS\SYSTEM)

VSVBX.LIC	Windows System directory


Entering topics

A picture of the main HelpDoc screen is shown below:

Click on any part of the picture above, or select from the list below:

Topic Tree

Context ID field

Exclude from doc?

Keywords field

Help text editor

Styles

Format Assistant


Topic Tree

A heirachical list of topics.

Click on an individual topic to see its details (Context ID, Keywords, Text etc).

Double-click (or press Enter) on entries marked with a '+' symbol to expand or contract it.


Context ID field

The reference number referred to in your application.


Exclude from doc?

If this option is selected, the topic appears in the Help File but does not appear in the manual.


Keywords field

This field allows you to define additional keywords.  Topic names are already supplied as keywords.  Keywords may consist of more than one word (key phrases) and should be separated by semi-colons.

Keywords entered in this field will become Index entries in the Manual.

Example

To add the keywords "copying files" and "copying" to a topic, type the following in the Keywords field for that topic:

copying files;copying

NOTE:	For best results when creating a manual, split nouns and verbs with a colon.  eg files:creating; files:modifying.  This will ensure that the index entries for the manual will appear more organised:

files

   creating  10

   modifying 10


Help text editor

Provides a facility to enter the text which will appear with the help topic.

Text will appear as normal text within the Help file (MS Sans Serif, 10 pt) and as Body Text in the word processing document.

If you wish to apply special styles, you should prefix a paragraph with one of the special formatting characters:

Prefix	Effect

 h/	Heading

 b/	Bullet

 g/	Puts the sub-items (child topics) of this topic in a list.  Neither this list nor the text that follows the g/ symbol will be displayed in the word processing document, but will appear in the help file.

For complete details on how to format your text, press the Format Assistant button within HelpDoc:


Styles

WCS HelpDoc provides a minimum number of formatting options.  This has been done because:

•	People who use WYSIWYG tools spend too much time playing with the formatting and not enough time entering text.

•	Professional documentation must be consistent and an over-abundance of formatting methods works against this.

•	Some Help-Authoring tools incorporate controls or widgets into which you place portions of your text.  This makes changing formatting or pasting large slabs of text very difficult.

To see the list of formatting styles, press the Format Assistant button:


Format Assistant

The Format Assistant provides instructions on how to format text to the style you need.

Click the pane showing the required formatting, and it will be replaced by instructions on how to achieve this effect.

Clicking the pane again causes the formatting to re-appear.


Editing topics

Once a number of topics have been entered, you will find yourself spending a lot of time on the following activities:

Navigating the file

Moving topics

Renaming topics

Finding Text

Replacing Text


Navigating the file

In addition to being able to select a particular topic from the Topic Tree using a mouse, WCS HelpDoc provides the following facilities for navigation:

Movement	Action

Topic up	Ctrl - Up

Topic down	Ctrl - Down

First topic	Ctrl - PageUp

Last topic	Ctrl - PageDown


Moving topics

Due to its heirachical nature, WCS HelpDoc allows you to create topics at any position within the heirachy (other than at the very top, being occupied by the 'contents' topic).

If you decide that a particular topic should be moved to another location:

•	Select the topic from the Topic Tree

•	Select 'Cut' from the Edit Menu.

•	Using the Topic Tree, select the topic before the position you want the topic to be moved to.

•	Select 'Paste' from the Edit Menu.


Renaming topics

Select Rename from the Topic Menu.


Finding Text

The Find option from the Edit Menu (or Ctrl-F) brings up a 'Find' dialog box.

WCS HelpDoc allows you to search for text contained within:

•	Topics

•	Text associated with topics

NOTE:	The search is NOT case sensitive, so searching for 'pROJECT' will find the same text as a search for the word 'project'.


Replacing Text

The Replace option from the Edit Menu (or Ctrl-R) brings up a 'Replace' dialog box.

Unlike the 'Find' facility, WCS HelpDoc only searches for text withing the 'Text' field of topics while replacing.


Objects

WCS HelpDoc provides strong integration of OLE objects.

From within the HelpDoc environment, you can:

•	Create new OLE objects and insert them into your text.

•	Create objects from existing files.

•	Add hypertext jumps to portions of the object.

See:

Object Viewer

Creating an object

Editing an object


Object Viewer

The Object Viewer is used to display OLE objects that you wish to embed into your application.

It is displayed when you:

•	Insert the object from the Edit Menu.

•	When you double-click on an existing object reference within the Help text editor.


Creating an object

There are three ways you may create an object:

Create a new object

•	Select 'Insert Object' from the Object menu.

•	Enter an appropriate name for the object or accept the default and press OK.

•	From the Object Viewer, select the New button.

•	Select the type of object to create

Create an object from a file

•	Select 'Insert Object' from the Object menu.

•	Select 'Create from File' and nominate the file you wish to include as your object.  Note that if you select 'Link' the object will not be stored in the HelpDoc file but be stored externally.

Paste an object into the file

•	From an OLE Server, select the area/items you want to include in your object and copy them

•	From WCS HelpDoc, select 'Insert Object' from the Object menu.

•	Select Paste from the Object Viewer.


Editing an object

Once an object has been created you may edit it simply by:

1.	Double-clicking the object reference (eg. <Object: Sample Object>) within the Help text editor.

2.	Pressing the Edit Object button on the Object Viewer.

You may wish to incorporate Hypergraphics in your object.  To do so:

•	Select the Hotspots button from the Object Viewer.

•	Once the Hotspot Editor is active, drag your mouse to create 'hotspots'.

•	Click the right mouse button over the newly-created hotspot.

•	Using Ctrl-Tab or Ctrl-Esc, switch to the WCS HelpDoc main screen.  Select the topic you want to jump to from the Topic Tree.

•	From the Topic Menu, select "Copy Context String".

•	Using Ctrl-Tab or Ctrl-Esc, switch to the Hotspot Editor and paste the context string into the edit box labelled "Context String".

•	Click 'OK'

NOTE:	Once an object has had hypergraphics added to it, a line will appear under the Hotspots button.  Editing the object by pressing the Edit Object button after hypergraphics have been added will destroy the hypergraphics.


Hypertext jumps

Unlike most help authoring tools, WCS HelpDoc provides hypertext links automatically.

This means that if there is a topic called "Setup", then every place that "Setup" appears in the text will appear highlighted and will jump to the "Setup" topic when it is clicked with the mouse.

The circumstances in which the automatic hypertext does not appear are detailed below:

•	If the case of the text does not match the case of the topic.  eg. "To setup the file..." will not match with the topic "Setup".

•	If the text appears within the topic itself.  The word "Setup" will not be highlighted if it appears within the "Setup" topic.

•	If the text appears within another word. eg. Setupfile does not match topic "Setup".


Configuring the System

Registered User Name

The name of the person using this product.

Company Name

The company to which this product is licensed, if applicable.

Registration Password

A password supplied by WCS to registered users.

Help Compiler Path

Indicate the full path of the help compiler (either hc31.exe or hcp.exe).  If you do not have a copy of the help compiler, it may be downloaded from the Microsoft Software Library on Compuserve.

HotSpot editor path

Indicate the full path of the Microsoft Hypergraphics Editor (shed.exe).  If you do not have a copy of the help compiler, it may be downloaded from the Microsoft Software Library on Compuserve.


Configuring a Project

Title

The title to appear on the title bar of the help file.

Copyright notice

The copyright notice informs the reader that no-one may copy portions of your work without your permission.  It is usually of the form:

Copyright 199x, <person or company name>

To insert the copyright symbol (), hold down the Alt key and press 0169 on the numeric keypad.

Template

When creating a manual, Word for Windows users should specify which MS Word template they wish to use as the basis for their manual.  See Creating MS Word Templates.


Creating a Manual

The following flow-chart illustrates the steps required in creating a complete manual:

The details are outlined below.


Specifying the file name

After selecting 'Create Word Document' from the file menu, you will be prompted for the name of the Word document you wish to create.


How HelpDoc creates a manual

When the user has nominated the file name of a manual to create from the 'Create Word Document' option of the File Menu, HelpDoc takes the following steps to create a manual:

1.	A new document is created using the template specified in Project Options.

2.	A table of contents is inserted

3.	Topics are inserted in the same order that they appear in the Topic Tree, with a heading style appropriate to its level of indentation.

4.	If there are any Keywords specified, an Index is appended to the end of the document containing those entries.


Creating MS Word Templates

There are several reasons why the default HelpDoc Word template may not be appropriate to your needs:

•	You want a different graphic on the title page.

•	You want different copyright information on page 2.

•	You want different heading styles.

•	You want a different page size.

It is recommended that the HelpDoc.Dot template supplied with this system be copied and modified to suit your requirements.

Which styles need to be defined?

Style	Application

Heading 1,2,3,4	Applied to topic headings.  The actual number depends on the heirachy level.  Those topics under the "contents" topic will be marked as Heading 1.  Topics under those will be Heading 2 etc.

NOTE:	You need to define as many heading styles as there are levels of indent.

Minor Heading	Applied to glossary items AND paragraphs prefixed by H/.

Rules for creating a template:

•	Ensure that all the styles noted above are defined

•	The page settings defined in the last section of the template will be used for the entire portion of the document that is created by HelpDoc.


Errors creating Word document

Errors may occur during the document-creation process, in which case a dialog box similar to the following will appear:

There are two main causes of these problems:

Microsoft Word is not in an appropriate state

Microsoft Word may not be in a position to respond to commands issued by HelpDoc.

Example:	If the 'Open' dialog box is active within Word, an error of this type will be generated.

In this situation:

•	Use Alt-Tab to bring up Microsoft Word

•	Restore Microsoft Word to its normal state.

•	Use Alt-Tab to return to WCS HelpDoc and press 'Retry'.

Formatting problems

Occasionly the format of the help file will not be compatible with the Template selected in Project Options.

Example:	If you create a topic with multiple tabs and the page width defined in the Word template is not large enough, an error will occur.

In this situation:

•	Use Alt-Tab to bring up Microsoft Word

•	Determine what portion of the document was being entered by HelpDoc.

•	Use Alt-Tab to return to WCS HelpDoc and press 'Cancel'

•	Adjust the portion of the HelpDoc file and/or Template and retry.


Menu Reference

Menu options available from the main screen:

File Menu

Edit Menu

Topic Menu

Options Menu

Help Menu


File Menu

New

Creates a new Help Database (HDB) file.

Open

Opens an existing Help Database file.

Close

Closes an existing Help Database file.

Save

A topic is saved automatically when you move to another topic, but if you are creating a large topic you may want to save it periodically.

Save As

Allows you to save the file under another name.

Import

Updates the help database file from a Visual Basic Mak file.  Before importing, you should assign a value to the HelpContextID for each of the forms and controls in your Visual Basic application which require context-sensitive help.  You must save your Visual Basic forms in text format for them to be recognised by the import routine.

The topics imported from Visual Basic will be in their raw control-name format, and should be renamed to something more meaningful.

Compact

After a period of time, especially if object are being created and deleted, the HelpDoc file will be larger than it needs to be.

Choose this option to reduce the size of the file.

Create Help File

Creates a Window help file (.hlp).  The file will have the same name as the HelpDoc file

Create Word Document

Creates a Word for Windows 6.0 document.  To use this option, you must have installed Word for Windows 6.0.

Test

Test the help topic.  Select any topic in the Topic Tree and press Ctrl-T to display it.  This option does not work if the topic in question was created after Create Help File was last selected.

Exit

Exit application.


Edit Menu

Cut

Cuts the whole topic to the clipboard.

Copy

Copies the whole topic to the clipboard.

Paste

Pastes a new topic next to the currently selected topic.

Find

Find a topic or text contained within a topic.

Find Next

Find the next occurance of search text within a topic name or topic text.

Replace

Replace occurences of text items.  Applies to topic text only.

Insert Object

Inserts a new object into the currently selected object.


Topic Menu

New

Creates a new topic.  You will be positioned on the Topic text box where you may immediately enter the topic name.

Rename

Allows you to rename the topic.

Delete

Deletes the currently selected topic.

Copy Context String

Copies the Context String for the currently selected topic to the clipboard.


Options Menu

Environment

Allows you to change global settings that apply to all projects.

Project

Allows you to change settings that apply only to the current project.


Help Menu

Contents

Brings up the main help screen.

Search for help on

Allows you to enter keywords.

How to use Help

Help file explaining how to navigate help files.

About

Copyright and Technical support information about this product.


Error Messages

Listed below are explanations for some of the errors that may appear during the operation of WCS HelpDoc.

Create an object first

Could not find SHED.EXE

Topic name too long to paste

Invalid topic format

Put new topic next to <topic>?

Cannot remove 'Contents' topic

The following objects were removed: <object list>

VB files saved in binary format

Topic name or Context ID already exists

Password is invalid

Invalid file name

Cannot delete topic with sub-topics

Could not find help compiler

Could not create new file using template: <name>

Nothing to paste


Create an object first

You cannot use the Hotspot editor to add hot-spots to an object's image until you have created an object.

Create an object by clicking on the "New" button of the Object Viewer.


Could not find SHED.EXE

The Microsoft Windows Hotspot Editor is missing or is not properly defined in the Environment Options.

This file is named shed.exe. The file is included with Visual Basic Professional, the Microsoft SDK (Software Development Kit), and most other Windows development tools.


Topic name too long to paste

A topic name may not be more than 50 characters.  The contents of the paste buffer is longer than 50 characters.


Invalid topic format

Topics may be pasted when the clipboard contains one of the following:

•	Text string up to 50 characters

•	A copy of a topic taken by selecting Cut or Copy from the Edit Menu.


Put new topic next to <topic>?

Select one of the following:

Yes

The new topic will be inserted at the same outline level as the current topic.

No

The new topic will be inserted as the first child of the currently selected topic.

Cancel

Abort operation.


Cannot remove 'Contents' topic

The 'contents' topic cannot be renamed or removed.  It is mandatory for every help file.


The following objects were removed: <object list>

During the compaction process, WCS HelpDoc removes all objects that are not referred to in the text.

For example, if you create an object:

<Object: Object 1>

and then decide you don't need it, you may simply delete the text.  The actual object, however, will remain in the HelpDoc file until the compaction process removes it.


VB files saved in binary format

One or more Visual Basic FRM files were saved in binary format, and could not be scanned for HelpContextID's.  If you want to have these files scanned,  open the relevant Visual Basic project and select the "Save as Text" in the Save As dialog box for the form files in question.


Topic name or Context ID already exists

New topics must have a unique Topic Name and a unique Context ID.  Visually scan the topics for duplicates.


Password is invalid

The password entered does not correspond to the Registered User Name and Company Name listed in the Environment Options.  Your password will be found in your User Manual.


Invalid file name

The file name should follow DOS naming conventions.  A file name should be no more than 8 characters long, or 12 characters if a three-character extension is specified.


Cannot delete topic with sub-topics

To delete topics with sub-topics, delete all the sub-topics individually first.


Could not find help compiler

The Microsoft Windows Help Compiler is missing or is not properly defined in the Environment Options.

This file is named hc31.exe or hcp.exe. The file is included with Visual Basic Professional, the Microsoft SDK (Software Development Kit), and most other Windows development tools.


Could not create new file using template: <name>

The template name specified in the Project Options screen does not exist.  See Configuring a Project.


Nothing to paste

A valid object does not appear on the clipboard.  The following steps may be used to overcome this:

•	Start an OLE server (eg. Windows Paintbrush)

•	Paste the data you wish to appear as an object

•	Select Copy from the edit menu of the Ole server

•	Re-select the Paste button from the Object Viewer.


Glossary

The major terms are defined below:

Context String

Hotspot Editor

Hypergraphics

Keywords

Sample Popup Topic

Topic


Context String

Internal identifier for topics.  If you need to refer to a topic from a Hypergraphic, use this indentifier.


Hotspot Editor

An utility used to add Hypergraphics to objects.


Hypergraphics

Graphics that jump.  In HelpDoc, any object (bitmap, graph, flowchart etc) may be modified so that it jumps to another topic when certain parts are pressed.


Keywords

Keywords are phrases linked to Topics.  When the user searches for a topic, he will be shown an alphabetical list of keyword phrases.  These phrases are automatically generated from topic names and merged with the phrases manually typed into the Keywords field.


Sample Popup Topic

This text describes the Sample Popup Topic.


Topic

The primary unit of information in a help file.  Topics are listed in the Topic Tree.